<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <title>Recoll Kio Slave</title>
</head>
<body>
  <a href="recoll:///search.html">Recoll search</a>
  <h2>Recoll kio slave</h2>

  <p>Use this module to perform Recoll searches from any program with
    a KIO interface.</p>

  <p>The module can work in two modes:</p>
  <ul>
    <li><b>Html interface</b>, close to a simplified QT Recoll
      interface.</li>
    <li><b>File manager interface</b>, <em>Only with KDE 4.1 and
	newer</em>, which presents results as directory entries</li>
  </ul>

  <p>With recent KDE versions (now: 2016), the file manager
    interface works in Dolphin, and both the file manager and the HTML
    interface work in Konqueror.</p>
  
  <p>You will undoubtedly obtain strange effects from time to time. If
    you have any remarks or ideas about improving kio_recoll, or
    observe an interesting and reproducible sequence,
    please <a href="mailto:jfd@recoll.org"> report it</a>.</p>

  <p>The module is particularly unhelpful with search hits inside
    email folders, which Konqueror or Dolphin have no way to access.</p>


  <h3>HTML interface</h3>

  <p>This works more or less like the Recoll QT GUI, much simplified. The 
    <a href="http://www.recoll.org/usermanual/rcl.search.lang.html">
      Recoll manual</a> describes the queries that can be performed.</p> 

  <p>Most pages in the interface should quite self-explanatory.</p>

  <p>You normally enter this interface by entering "recoll:" or
    "recoll:/" in the Konqueror URL entry, and following the "search"
    link. You can also directly enter "recoll:/search.html".<br>  

    In most circumstances, entering a link like
    <a href="recoll:/john smith">recoll:/john smith</a> will also
    yield an HTML result list.</p>

  <p>Compared to QT Recoll, the nice point is that you can click or
    drag/drop the icons to access the results in the standard desktop
    way.</p>

  <h3>File manager interface</h3>

  <p>The <i>path</i> part of the URI is taken as a Recoll query
    language string and executed. The results are displayed as
    directory entries.</p>

  <p>There are several ways to enter this interface:</p>
  <ul>
    <li>Dolphin will only present the file manager interface. Enter
      <i>recoll:/some&nbsp;query</i>
      or <i>recoll:&nbsp;some&nbsp;query</i> in the address bar. Note: 
      single-slash, not double, you will get something like "Protocol
      unknown" if you enter 2 slashes.</li>

    <li>Konqueror: this supports both the file manager and HTML
    interfaces. You can force using the file manager interface in the
      following ways:
      <ul>
        <li>Using "recollf" as protocol name instead of "recoll". This is
          probably the easiest option inside open dialogs.</li>

        <li>Using an URL ending with a&nbsp;'/', ie:
          <blockquote>
	    <a href="recoll:/red apples ext:html/">
	      recoll:/red apples ext:html/</a>
          </blockquote>
        </li>
        <li>If you would like to use the file manager view most of the
          time, you can set the <code>RECOLL_KIO_ALWAYS_DIR</code> environment
          variable or the <code>kio_always_dir</code> recoll.conf variable
          to&nbsp;1. The HTML interface will then only be accessible
          through the search link in the top "recoll:" view.</li>
      </ul>
  </ul>

  <p>No search result details (samples, relevance etc.) are available,
    but this interface allows multiple selections and copies, usage
    inside any KDE open dialog, etc.</p>

  <p>To avoid swamping the interface with too many thousands of
    results, the result count is limited to 10000 by default. You can
    change this value by setting the <code>kio_max_direntries</code>
    parameter in your recoll configuration file (typically
    ~/.recoll/recoll.conf)</p>

  <p><a href="recoll:///search.html">Recoll Search</a></p>

</body>
</html>
